/*
 * Copyright (C) 2025 Tsingteng MicroSystem
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/**
 * @file rf_discover.h
 * @brief 定义用于模块内访问的RF Discovery相关接口
 */

#ifndef _DISCOVER_INT_H_
#define _DISCOVER_INT_H_

#include "nci_base.h"
#include "nci_rf.h"
#include "nci_feature.h"

/**
 * @brief 多协议卡片被发现时回调
 *
 * @param p_params 发现参数
 *
 * @return 成功返回NCI_STATUS_OK，失败返回其他错误码
 */
tNCI_STATUS on_rf_discovered(tNCI_RF_DISCOVER_PARAMS *p_params);
/**
 * @brief 处理RF接口激活的事件
 *
 * @param p_params 激活参数
 *
 * @return 成功返回NCI_STATUS_OK，失败返回其他错误码
 */
tNCI_STATUS on_rf_intf_activated(tNCI_RF_INTF_ACTIVATED_PARAMS *p_params);
/**
 * @brief 处理RF接口去激活事件
 *
 * @param type 去激活的类型
 * @param reason 去激活的原因
 *
 * @return 成功返回NCI_STATUS_OK，失败返回其他错误码
 */
tNCI_STATUS on_rf_deactivated(tNCI_RF_DEACTIVATE_TYPE type, tNCI_RF_DEACTIVATE_REASON reason);
/**
 * @brief 处理RF接口错误事件
 *
 * @param status 状态码
 */
void on_rf_error(tNCI_STATUS status);
/**
 * @brief 获取RF锁
 *
 * @note 获取锁成功后，调用者需要调用rf_unlock()释放锁
 *
 * @return 成功返回NCI_STATUS_OK，失败返回其他错误码
 */
tNCI_STATUS rf_lock();

/**
 * @brief 释放RF锁
 *
 * @note 调用者需要先调用rf_lock()获取锁，然后才能调用此函数释放锁
 *
 * @return 成功返回NCI_STATUS_OK，失败返回其他错误码
 */
tNCI_STATUS rf_unlock();

/**
 * @brief 设置RF Discover参数
 *
 * @param poll_param POLLING参数
 * @param listen_param LISTENING参数
 *
 * @note poll_param和listen_param为负数的情况表示此项参数保持原样，不修改
 * @note 此函数只是设置poll和listen参数，RF状态不会改变
 *
 * @return 成功返回NCI_STATUS_OK，失败返回其他错误码
 */
tNCI_STATUS rf_set_discover_param(int poll_param, int listen_param);

#if IS_FEATURE_ON(NCI_FEATURE_RW)
/**
 * @brief 选择卡片进行激活
 *
 * @param id 被激活的卡片ID
 * @param protocol 使用哪种协议激活
 * @param interface 使用哪个接口激活
 * @param timeout 等待激活超时时间
 * @param p_activated_data 激活后返回的参数，如果为NULL则不等待激活
 *
 * @return 成功返回NCI_STATUS_OK，失败返回其他错误码
 */
tNCI_STATUS rf_select(tNCI_RF_DISCOVERY_ID id, tNCI_RF_PROTOCOL protocol, tNCI_RF_INTERFACE interface, uint32_t timeout, tNCI_RF_INTF_ACTIVATED_PARAMS *p_activated_data);

/**
 * @brief 重新选择卡片进行激活
 *
 * @note 要求当前状态为POLL_ACTIVE
 * @note 会先sleep，再重新选择激活
 *
 * @param id 被激活的卡片ID
 * @param protocol 使用哪种协议激活
 * @param interface 使用哪个接口激活
 * @param timeout 等待激活超时时间
 *
 * @return 成功返回NCI_STATUS_OK，失败返回其他错误码
 */
tNCI_STATUS rf_re_select(tNCI_RF_DISCOVERY_ID id, tNCI_RF_PROTOCOL protocol, tNCI_RF_INTERFACE interface, uint32_t timeout);
#endif // IS_FEATURE_ON(NCI_FEATURE_RW)

#if IS_FEATURE_ON(NCI_FEATURE_RW_T3T)
/**
 * @brief 发送T3T识别码
 * @param[in] sensf_req T3T识别码请求参数
 * @param[out] sensf_res_list T3T识别码响应列表
 * @param[inout] res_count 返回的T3T识别码响应列表个数, 传入时为最大返回个数，返回时为实际返回个数
 * @return 成功返回NCI_STATUS_OK，失败返回其他错误码
 */
tNCI_STATUS rf_t3t_polling(tNCI_RF_SENSF_REQ_PARAMS sensf_req, tNCI_RF_SENSF_RES *sensf_res_list, uint8_t *res_count);
#endif // IS_FEATURE_ON(NCI_FEATURE_RW_T3T)

#if IS_FEATURE_ON(NCI_FEATURE_RW_T4T)
/**
 * @brief 发送T4T NAK_PRESENCE指令
 * @note 只有在当前RF状态为NCI_RFST_POLL_ACTIVE时才能发送此指令
 * @return 成功返回NCI_STATUS_OK，失败返回其他错误码
 */
tNCI_STATUS rf_t4t_nak_presence();
#endif // IS_FEATURE_ON(NCI_FEATURE_RW_T4T)

#if IS_FEATURE_ON(NCI_FEATURE_RW) || IS_FEATURE_ON(NCI_FEATURE_CE)
/**
 * @brief 去激活
 *
 * @note 当当前状态为NCI_RFST_POLL_ACTIVE或NCI_RFST_LISTEN_ACTIVE时，调用此函数可以切换到SLEEP或Discovery状态
 * @note 当当前状态为NCI_RFST_W4_ALL_DISCOVERIES时，调用此函数可以切换到IDLE状态
 *
 * @param is_sleep 是否切换到SLEEP状态，true为切换到SLEEP状态，false为切换到Discovery状态
 *
 * @return 成功返回NCI_STATUS_OK，失败返回其他错误码
 */
tNCI_STATUS rf_deactivate(bool is_sleep);
/**
 * @brief 向RF通道发送Data数据
 *
 * @note 只有在POLL_ACTIVE或LISTEN_ACTIVE状态才能发送Data数据
 *
 * @param[in] cmd 待发送的Data数据
 * @param[out] rsp 接收到的Data数据
 * @param[in] timeout 等待rsp的超时时间
 *
 * @return 成功返回NCI_STATUS_OK，失败返回其他错误码
 */
tNCI_STATUS rf_transmit(tNCI_BUF *cmd, tNCI_BUF *rsp, uint32_t timeout);
/**
 * @brief 向RF通道发送Data数据,异步方式，不等待RSP
 *
 * @note 只有在POLL_ACTIVE或LISTEN_ACTIVE状态才能发送Data数据
 *
 * @param[in] cmd 待发送的Data数据
 *
 * @return 成功返回NCI_STATUS_OK，失败返回其他错误码
 */
tNCI_STATUS rf_transmit_async(tNCI_BUF *cmd);
#endif // IS_FEATURE_ON(NCI_FEATURE_RW) || IS_FEATURE_ON(NCI_FEATURE_CE)

#endif /* _DISCOVER_INT_H_ */
